Add Tor Hidden Service instructions to Full Node guide by refined-element · Pull Request #4609 · bitcoin-dot-org/Bitcoin.org

refined-element · 2026-01-28T21:19:40Z

Summary

This PR adds comprehensive instructions for running a Bitcoin full node as a Tor hidden service to the full-node.md guide.

Changes include:

Why Run a Tor Hidden Service: Benefits including privacy, censorship resistance, and no port forwarding required
Installing Tor: Step-by-step instructions for Linux (Debian/Ubuntu, Fedora, Arch), Windows, and macOS
Configuring Tor Hidden Service: How to edit torrc and create the hidden service
Configuring Bitcoin Core: Complete bitcoin.conf settings for Tor integration
Verification: How to confirm the hidden service is working using bitcoin-cli
Troubleshooting: Common issues and solutions

The section is placed after "Network Configuration" and before "Configuration Tuning" in the document structure, and will automatically appear in the auto-generated table of contents.

Addresses

This PR addresses bounty #1712: "Add instructions for Running a Full Node as a Tor Hidden Service"
#1712

Payment Address

Bitcoin address for bounty payment: bc1qax8d6etvphms3tqqc7hy52vas4af7ezv4msvqd

🤖 Generated with Claude Code

Add comprehensive section on running a Bitcoin full node as a Tor hidden service, including: - Benefits of running as a hidden service (privacy, censorship resistance) - Installation instructions for Linux, Windows, and macOS - Tor hidden service configuration - Bitcoin Core configuration for Tor - Verification steps and troubleshooting Addresses bounty bitcoin-dot-org#1712 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Copilot

Pull request overview

This PR adds comprehensive instructions for configuring Bitcoin Core to run as a Tor hidden service to the full-node.md documentation. The guide addresses issue #1712 and provides step-by-step instructions to help users enhance their node's privacy and accessibility.

Changes:

Added a new "Running as a Tor Hidden Service" section between Network Configuration and Configuration Tuning
Includes installation instructions for Tor on Linux, Windows, and macOS
Provides torrc configuration guidance and Bitcoin Core configuration examples
Includes verification steps and troubleshooting tips

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-28T21:25:29Z

en/full-node.md

+
+    HiddenServiceDir /var/lib/tor/bitcoin-service/
+    HiddenServicePort 8333 127.0.0.1:8333
+


The HiddenServiceDir path /var/lib/tor/bitcoin-service/ is correct for Linux, but on macOS when using Homebrew, the Tor data directory should typically be under /usr/local/var/lib/tor/ (Intel) or /opt/homebrew/var/lib/tor/ (Apple Silicon). This inconsistency will cause issues when macOS users try to find their hidden service hostname file at line 1412. Consider adding a platform-specific note or updating the path for macOS users.

Suggested change

HiddenServiceDir /var/lib/tor/bitcoin-service/

HiddenServicePort 8333 127.0.0.1:8333

**Linux**

HiddenServiceDir /var/lib/tor/bitcoin-service/

HiddenServicePort 8333 127.0.0.1:8333

**macOS (Apple Silicon, Homebrew default)**

HiddenServiceDir /opt/homebrew/var/lib/tor/bitcoin-service/

HiddenServicePort 8333 127.0.0.1:8333

**macOS (Intel, Homebrew default)**

HiddenServiceDir /usr/local/var/lib/tor/bitcoin-service/

HiddenServicePort 8333 127.0.0.1:8333

Copilot · 2026-01-28T21:25:29Z

en/full-node.md

+3. Open a Command Prompt as Administrator
+4. Navigate to the Tor directory and run: `tor.exe --service install`


The Windows installation instructions suggest running tor.exe --service install from the command line, but this requires administrative privileges and installs Tor as a Windows service. However, there's no guidance on how to configure the torrc file before installing the service, or how to start/stop the service after installation. Consider adding steps to configure torrc first, and instructions on managing the service (e.g., using net start tor and net stop tor).

Suggested change

3. Open a Command Prompt as Administrator

4. Navigate to the Tor directory and run: `tor.exe --service install`

3. Create or edit a Tor configuration file (`torrc`) in a suitable location (for example, `C:\Tor\Data\Tor\torrc`) and add your desired settings.

4. Open a Command Prompt as Administrator.

5. Navigate to the Tor directory and install Tor as a Windows service:

`tor.exe --service install`

6. After installation, you can manage the Tor service from an Administrator Command Prompt using:

* Start: `net start tor`

* Stop: `net stop tor`

You can also manage the service via the Windows “Services” management console (`services.msc`).

Copilot · 2026-01-28T21:25:29Z

en/full-node.md

+sudo cat /var/lib/tor/bitcoin-service/hostname
+
+## macOS
+cat /var/lib/tor/bitcoin-service/hostname


Instructions for viewing the hidden service hostname are provided for Linux and macOS but not for Windows. Windows users need to know how to view their .onion address (e.g., using type C:\Tor\bitcoin-service\hostname in Command Prompt or opening the file in Notepad). Add Windows-specific instructions.

Suggested change

cat /var/lib/tor/bitcoin-service/hostname

cat /var/lib/tor/bitcoin-service/hostname

## Windows (Command Prompt)

type C:\Tor\bitcoin-service\hostname

Copilot · 2026-01-28T21:25:30Z

en/full-node.md

+**Tor service not running**: Ensure Tor is started and check its status:
+{% highlight bash %}
+sudo systemctl status tor
+{% endhighlight %}
+
+**Hidden service directory permissions**: Tor requires specific permissions on the hidden service directory. If you see permission errors, the directory should be owned by the Tor user (usually `debian-tor` on Debian/Ubuntu or `tor` on other systems):
+{% highlight bash %}
+sudo chown -R debian-tor:debian-tor /var/lib/tor/bitcoin-service/
+sudo chmod 700 /var/lib/tor/bitcoin-service/
+{% endhighlight %}
+
+**Bitcoin Core can't connect through proxy**: Verify Tor is listening on port 9050:
+{% highlight bash %}
+ss -tlnp | grep 9050
+{% endhighlight %}
+


The troubleshooting section provides only Linux-specific commands (systemctl status tor, ss -tlnp | grep 9050). Windows and macOS users experiencing issues won't be able to use these commands. Consider adding platform-specific alternatives (e.g., for Windows: checking Services.msc for Tor service status, using netstat -an | findstr 9050 to check if Tor is listening).

Suggested change

**Tor service not running**: Ensure Tor is started and check its status:

{% highlight bash %}

sudo systemctl status tor

{% endhighlight %}

**Hidden service directory permissions**: Tor requires specific permissions on the hidden service directory. If you see permission errors, the directory should be owned by the Tor user (usually `debian-tor` on Debian/Ubuntu or `tor` on other systems):

{% highlight bash %}

sudo chown -R debian-tor:debian-tor /var/lib/tor/bitcoin-service/

sudo chmod 700 /var/lib/tor/bitcoin-service/

{% endhighlight %}

**Bitcoin Core can't connect through proxy**: Verify Tor is listening on port 9050:

{% highlight bash %}

ss -tlnp | grep 9050

{% endhighlight %}

**Tor service not running**: Ensure Tor is started and check its status.

*On Linux (systemd-based distributions):*

{% highlight bash %}

sudo systemctl status tor

{% endhighlight %}

*On Windows:*

- If you installed Tor as a service, open `services.msc` and check that the **Tor** service is running.

- If you use Tor Browser, make sure Tor Browser is open and connected.

*On macOS (Homebrew installation):*

{% highlight bash %}

brew services list | grep tor

{% endhighlight %}

**Hidden service directory permissions**: Tor requires specific permissions on the hidden service directory. If you see permission errors, the directory should be owned by the Tor user (usually `debian-tor` on Debian/Ubuntu or `tor` on other systems):

{% highlight bash %}

sudo chown -R debian-tor:debian-tor /var/lib/tor/bitcoin-service/

sudo chmod 700 /var/lib/tor/bitcoin-service/

{% endhighlight %}

**Bitcoin Core can't connect through proxy**: Verify Tor is listening on port 9050.

*On Linux:*

{% highlight bash %}

ss -tlnp | grep 9050

{% endhighlight %}

*On Windows (Command Prompt):*

{% highlight bash %}

netstat -an | findstr 9050

{% endhighlight %}

*On Windows (PowerShell):*

{% highlight bash %}

Get-NetTCPConnection -LocalPort 9050

{% endhighlight %}

*On macOS:*

{% highlight bash %}

netstat -an | grep 9050

{% endhighlight %}

Copilot · 2026-01-28T21:25:30Z

en/full-node.md

+    ## Explicitly allow connections to IPv4 and onion networks
+    onlynet=ipv4
+    onlynet=onion
+


The "Verifying Your Hidden Service" section begins with "After restarting Bitcoin Core" but there are no explicit instructions to restart Bitcoin Core after modifying bitcoin.conf. While experienced users may understand this is necessary, adding an explicit instruction to restart Bitcoin Core after saving the bitcoin.conf changes would improve clarity for novice users.

Suggested change

After saving your changes to `bitcoin.conf`, restart Bitcoin Core to apply the new Tor settings.

Copilot · 2026-01-28T21:25:30Z

en/full-node.md

+    ## Enable listening for incoming connections
+    listen=1
+
+    ## Connect through the Tor SOCKS proxy
+    proxy=127.0.0.1:9050
+
+    ## Bind to localhost for the hidden service
+    bind=127.0.0.1
+
+    ## Tell Bitcoin Core about your onion address (replace with your actual .onion address)
+    externalip=youronionaddress.onion
+
+    ## Only connect to .onion addresses (optional, for maximum privacy)
+    #onlynet=onion


The bitcoin.conf configuration uses double hash marks (##) for comments, but Bitcoin Core's configuration file format uses single hash marks (#) for comments. This is inconsistent with Bitcoin Core's standard configuration format and could confuse users. Change all ## to # in the configuration examples.

Copilot · 2026-01-28T21:25:30Z

en/full-node.md

+    proxy=127.0.0.1:9050
+    externalip=youronionaddress.onion
+
+    ## Explicitly allow connections to IPv4 and onion networks


The configuration comment uses double hash marks (##) but Bitcoin Core's configuration file format uses single hash marks (#). Change ## to # for consistency with Bitcoin Core's standard configuration format.

Copilot · 2026-01-28T21:25:31Z

en/full-node.md

+## macOS
+cat /var/lib/tor/bitcoin-service/hostname


The command to view the hidden service hostname on macOS specifies /var/lib/tor/bitcoin-service/hostname, but this path is inconsistent with the macOS Tor data directory. When Tor is installed via Homebrew on macOS, the hidden service directory should be located under /usr/local/var/lib/tor/ (Intel) or /opt/homebrew/var/lib/tor/ (Apple Silicon). Update this command to use the correct macOS path or add a note about the platform-specific location.

Copilot · 2026-01-28T21:25:31Z

en/full-node.md

+sudo systemctl restart tor
+
+## macOS
+brew services restart tor


The instructions for restarting Tor after editing the torrc file are provided only for Linux and macOS, but not for Windows. Windows users who install Tor as a service need instructions on how to restart it (e.g., using net stop tor followed by net start tor in an Administrator Command Prompt, or using the Services management console). Add Windows-specific instructions for restarting the Tor service.

Suggested change

brew services restart tor

brew services restart tor

## Windows

:: From an Administrator Command Prompt:

net stop tor

net start tor

:: Or use the Services management console (services.msc)

Copilot · 2026-01-28T21:25:31Z

en/full-node.md

+If you want your node to connect to both regular IPv4/IPv6 nodes AND Tor nodes, use this configuration instead:
+
+    listen=1
+    bind=127.0.0.1
+    proxy=127.0.0.1:9050
+    externalip=youronionaddress.onion
+
+    ## Explicitly allow connections to IPv4 and onion networks
+    onlynet=ipv4
+    onlynet=onion


The configuration uses bind=127.0.0.1 which binds Bitcoin Core only to localhost. This is correct for a Tor-only setup, but for the dual configuration (IPv4 + Tor) shown in the second example, this may prevent IPv4 connections from working properly unless users also configure port forwarding to localhost. Consider clarifying that bind=127.0.0.1 is specifically for the hidden service and that users running dual-stack should understand the implications, or provide a more complete dual-stack configuration example.

Copilot AI review requested due to automatic review settings January 28, 2026 21:19

Copilot started reviewing on behalf of refined-element January 28, 2026 21:20 View session

Copilot AI reviewed Jan 28, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Tor Hidden Service instructions to Full Node guide#4609

Add Tor Hidden Service instructions to Full Node guide#4609
refined-element wants to merge 1 commit intobitcoin-dot-org:masterfrom
refined-element:add-tor-hidden-service

refined-element commented Jan 28, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 28, 2026

Uh oh!

Copilot AI Jan 28, 2026

Uh oh!

Copilot AI Jan 28, 2026

Uh oh!

Copilot AI Jan 28, 2026

Uh oh!

Copilot AI Jan 28, 2026

Uh oh!

Copilot AI Jan 28, 2026

Uh oh!

Copilot AI Jan 28, 2026

Uh oh!

Copilot AI Jan 28, 2026

Uh oh!

Copilot AI Jan 28, 2026

Uh oh!

Copilot AI Jan 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		HiddenServiceDir /var/lib/tor/bitcoin-service/
		HiddenServicePort 8333 127.0.0.1:8333

		3. Open a Command Prompt as Administrator
		4. Navigate to the Tor directory and run: `tor.exe --service install`

-. Open a Command Prompt as Administrator
-. Navigate to the Tor directory and run: `tor.exe --service install`
+. Create or edit a Tor configuration file (`torrc`) in a suitable location (for example, `C:\Tor\Data\Tor\torrc`) and add your desired settings.
+. Open a Command Prompt as Administrator.
+. Navigate to the Tor directory and install Tor as a Windows service:
+   `tor.exe --service install`
+. After installation, you can manage the Tor service from an Administrator Command Prompt using:
+   * Start: `net start tor`
+   * Stop: `net stop tor`
+   You can also manage the service via the Windows “Services” management console (`services.msc`).



	After saving your changes to `bitcoin.conf`, restart Bitcoin Core to apply the new Tor settings.

Conversation

refined-element commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes include:

Addresses

Payment Address

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

refined-element commented Jan 28, 2026 •

edited

Loading